19. Appendix B Command Line Interface (CLI) Programmer¶
19.1. CLI Programmer – Overview¶
cli_programmer is a command line tool for reading & writing to FLASH/OTP/RAM. It also provides some extra functions like loading & executing an image from RAM. The tool communicates with the target device over uart port or swd/jtag interface. It executes on Windows and Linux platforms.
Note
Writing an image to flash requires adding a header to the image. This process is handled by the bin2image tool, or the cli_programmer write_qspi_exec command.
19.2. Application command description¶
Open a terminal and navigate to the folder <sdk_root_directory>/binaries/ To run cli_programmer the interface (GDB server or serial port) and the requested command must be supplied.
> cli_programmer [<options>] <interface> <command> [<args>]
For the interface name the user must use the name presented by the operating system. For the serial port the file name is e.g. COM5 (Windows) or /dev/ttyUSB0 (Linux) and for the SWD interface (J-Link debugger with the GDB server) is gdbserver.
| Option | Description |
|---|---|
| write_qspi <address> <file> [<size>] | Writes up to size bytes of file into the FLASH at address. If size is omitted, a complete file is written. |
| write_qspi_bytes <address> <data1> [<data2> […]] | Writes bytes specified on command line into the FLASH at address. |
| write_qspi_exec <image_file> | Writes binary file (.bin) to flash at address 0, after adding header for execution in place (cached mode). |
| write_suota_image <image_file> <version> | Writes SUOTA enabled image_file to executable partition. The user supplied version string goes to image header. |
| read_qspi <address> <file> <size> | Reads size bytes from the FLASH memory, starting at address into file. If file is specified as either ‘-‘ or ‘–’, data is output to stdout as hexdump. The hexdump is either 16-bytes (-) or 32-bytes (–) wide. |
| erase_qspi <address> <size> | Erases size bytes of the FLASH, starting at address. Note: an actual erased area may be different due to the size of an erase block. |
| chip_erase_qspi | Erases the whole FLASH. |
| copy_qspi <address_ram> <address_qspi> <size> | Copies size bytes from the RAM memory, starting at address_ram to FLASH at address_flash. This is an advanced command and is not needed by end user. |
| is_empty_qspi [start_address size] | Checks that FLASH contains only 0xFF values. If no arguments are specified starting address is 0 and size is 1M. Command prints whether flash is empty and if offset of first non-empty byte. |
| read_partition_table | Reads the partition table (if any exists) and prints its contents. |
| write <address> <file> [<size>] | Writes up to size bytes of file into the RAM memory at address. If size is omitted, a complete file is written. |
| read <address> <file> <size> | Reads size bytes from the RAM memory, starting at address into file. If file is specified as either ‘-‘ or ‘–’, data is output to stdout as hexdump. The hexdump is either 16-bytes (-) or 32-bytes (–) wide. |
| write_otp <address> <length> [<data> [<data> […]]] | Writes
|
| read_otp <address> <length> | Reads length 32-bit words from the OTP address address. |
| write_otp_file <file> | Writes data to the OTP as defined in file (default specified values are written). |
| read_otp_file <file> | Reads data from the OTP as defined in file (cells with default value provided are read) contents of each cell is printed to stdout. |
| write_tcs <length> [<reg_addr> <reg_data> [<reg_addr> <reg_data> […]]] | Writes size |
| Boot | Boots the 2nd stage bootloader or the application binary (defined with -b) and exits. |
| read_chip_info | Reads chip information from chip revision registers and OTP header. |
| Option | Description |
|---|---|
| -h | Prints help screen and exits. |
| –save-ini | Saves CLI programmer configuration to the cli_programmer.ini file and exits. |
| -b file | Filename of 2nd stage bootloader or an application binary. |
| Option | Description |
|---|---|
| -p <port_num> | TCP port number that GDB server listens to. The Default value is 2331. |
| -r <host> | GNU server host. The default is localhost. |
| –no-kill | Don’t stop already running GDB server instance. |
| –gdb-cmd <cmd> | GDB server command used for executing and passing the right parameters to GDB server. |
Without this parameter no GDB server instance will be started or
stopped. As GDB server command line can be quite long, to avoid typing
it every time the tool is executed and the best way to store this
command line in cli_programmer.ini file is by using the --save-ini
command line option.
| Option | Description |
|---|---|
| -s <baudrate> | Baud rate used for UART by uartboot. The parameter is patched to the uploaded uartboot binary (in that way passed as a parameter). This can be 9600, 19200, 57600 (default), 115200, 230400, 500000, 1000000. |
| -i <baudrate> | Initial baud rate used for uploading the uartboot or a user supplied binary. This depends on the rate used by the bootloader of the device. The default behavior is to use the value passed by -s or its default, if the parameter is not given. The argument is ignored by the boot command. -s option should be used in this case. |
| –tx-port <port_num> | GPIO port used for UART Tx by the uartboot. This parameter is patched to the uploaded uartboot binary (in that way passed as a parameter). The default value is 1. This argument is ignored when the boot command is given. |
| –tx-pin <pin_num> | GPIO pin used for UART Tx by uartboot. This parameter is patched to the uploaded uartboot binary (in that way passed as a parameter). The default value is 3. The argument is ignored when the boot command is givern. |
| –rx-port <port_num> | GPIO port used for UART Rx by uartboot. This parameter is patched to the uploaded uartboot binary (in that way passed as a parameter). The default value is 2. The argument is ignored when the boot command is given. |
| –rx-pin <pin_num> | GPIO pin used for UART Rx by uartboot. This parameter is patched to the uploaded uartboot binary (in that way passed as a parameter). The default value is 3. The argument is ignored when the boot command is given. |
| -w timeout | Serial port communication timeout is used only during download of uartboot binary, if during this time board will not respond cli_programmer exits with timeout error. |
| Option | Description |
|---|---|
| –prod-id DA14681-01 | DA14680-01, DA14681-01. Selects the chip product ID. This option applies only when It instructs |
When cli_programmer is executed it tries to read the cli_programmer.ini file which may contain various cli_programmer options. Instead of creating this file manually, the user should use the --save-ini command line option. The format of the cli_programmer.ini adheres to standard Windows ini file syntax. The cli_programmer looks for ini file in the following locations:
- current directory
- home directory
cli_programmerexecutable directory
19.3. Command examples¶
Example 1
Upload binary data to FLASH.
Windows:
> cli_programmer COM40 write_qspi 0x0 data_i
Linux:
> cli_programmer /dev/ttyUSB0 write_qspi 0x0 data_i
Example 2
Upload binary data to FLASH using maximum serial port baudrate.
> cli_programmer -s 1000000 -i 57600 COM40 write_qspi 0x0 data_i
Example 3
Read data from FLASH to local file.
> cli_programmer COM40 read_qspi 0x0 data_o 0x100
Example 4
Upload custom binary test_api.bin to RAM and execute it.
> cli_programmer -b test_api.bin COM40 boot
Example 5
Upload custom binary `test_api.bin` to RAM and execute it, using UART
Tx/Rx P1_3/P2_3 (uses boot rom booter baud rate ata 9600)
> cli_programmer –s 9600 -b test_api.bin COM40 boot
Example 6
Modify FLASH at specified location with arguments passed in command line.
> cli_programmer COM40 write_qspi_bytes 0x80000 0x11 0x22 0x33
Example 7
Run a few commands with uartboot, using UART Tx/Rx P1_3/P2_3 at baud
rate 115200
(initial rate for uartboot uploading must be 9600 ).
> cli_programmer -i 9600 -s 115200 --tx-port 1 --tx-pin 3 --rx-port 2 --rx-pin 3 COM40 write_qspi 0x0 data_i
> cli_programmer -i 9600 -s 115200 --tx-port 1 --tx-pin 3 --rx-port 2 --rx-pin 3 COM40 read_qspi 0x0 data_o 0x100
Example 8
Run a few commands with uartboot, using UART Tx/Rx P1_3/P2_3 at baud
rate 115200
(initial rate for uartboot uploading is 9600).
> cli_programmer -i 9600 -s 115200 --tx-port 1 --tx-pin 3 --rx-port 2 --rx-pin 3 COM40 write_qspi 0x0 data_i
> cli_programmer -i 9600 -s 115200 --tx-port 1 --tx-pin 3 --rx-port 2 --rx-pin 3 COM40 read_qspi 0x0 data_o 0x100
Example 9
Read FLASH contents (10 bytes at address 0x0).
Start gdbserver manually!
> cli_programmer gdbserver read_qspi 0 -- 10
Example 10
Write register 0x50003000 with value 0x00FF and register 0x50003002 with
value 0x00AA.
> cli_programmer gdbserver write_tcs 4 0x50003000 0x00FF 0x50003002 0x00AA
Example 11
Write settings to the cli_programmer.ini file. Long bootloader path is passed with -b option and command line to start GDB server is passed with --gdb-cmd. In this example GDB server command line contains arguments and path to executable has space so whole command line is put in quotes and quotes required by Windows path are additionally escaped.
> cli_programmer –b c:/users/jon/<sdk_root_directory>/bsp/system/loaders/uartboot/Release/uartboot.bin --save-ini --gdb-cmd "/"C:/Program Files/SEGGER/JLink_V510d/JLinkGDBServerCL.exe" -if SWD -device Cortex-M0 -singlerun -silent -speed auto
Example 12
Program a DA14681-01 chip with an executable flash image.
> cli_programmer --prod-id DA14681-01 gdbserver write_qspi_exec ../../../../projects/dk_apps/features/tickless/DA14681-01-Debug_QSPI/tickless.bin
Example 13
Write 6 bytes specified in command line to flash at address 0x80000.
> cli_programmer gdbserver write_qspi_bytes 0x80000 0x11 0x22 0x33
0x44 0x55 0x66
Example 14
Write SUOTA enable application to proper location in flash.
> cli_programmer gdbserver write_suota_image pxp_reporter.bin “1.1.0.1 a”
Example 15
Write OTP address 0x07f80128 with the following contents: B0:0x00, B1:0x01, B2:0x02, B3:0x03, B4:0x04, B5:0x05, B6:0x06, B7:0x07
> cli_programmer gdbserver write_otp 0x07f80128 2 0x03020100 0x07060504
Read OTP address 0x07f80128.
> cli_programmer gdbserver read_otp 0x07f80128 2
If written with the contents from above write example, it should return:
``0025 00 01 02 03 04 05 06 07 ……….. ``
19.3.1. Installation and debugging procedure¶
The cli_programmer make use of the libprogrammer library which implements the underlying functionality on the host side. The cli_programmer can be linked either statically or dynamically with libprogrammer.
The cli_programmer uses uartboot application which acts as a secondary bootloader which cli_programmer downloads to the target for performing the read/write operations.
The project is found in <sdk_root_directory>/utilities/cli_programmer/cli.
| Configuration | Description |
|---|---|
| Debug | Debug version for Linux. |
| Debug_static | Debug version linked with a static version of the libprogrammer and it’s recommended for Linux. It also builds uartboot project and includes it in cli_programmer executable. |
| Debug_static_win32 | Debug version for Windows linked with a static version of libprogrammer. |
| Release | Release version for Linux. |
| Release_static | Release version linked with a static version of libprogrammer and it’s recommended for Linux. It also builds uartboot project and includes it in cli_programmer executable. |
| Release_static_win32 | Release version for Windows linked with a static version of libprogrammer. |
19.3.2. Build instructions¶
Build instructions:
- Import libprogrammer, cli_programmer and uartboot into SmartSnippets™ Studio
- Build libprogrammer , cli_programmer and uartboot in Release_static configuration (recommended)
Run cli_programmer with proper parameters as described in 19.2 and 19.3.
Note
A prebuilt version of cli_programmer can be found under SmartSnippets™ DA1468x SDK’s binaries folder.